/*
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.googlecode.j4sc.submission.manager;

import com.googlecode.j4sc.conversion.Conversion;
import com.googlecode.j4sc.submission.SubmissionReference;

/**
 * After registering a ConversionListener with a {@link SubmissionManager},
 * using the {@link SubmissionManager#addListener(ConversionListener)} method,
 * on events being triggered as a result of retrieval, a method on this
 * interface will be called allowing handling of the particular event
 * 
 * @author Raj Patel, Dariusz Lorenc
 */
public interface ConversionListener {

    /**
     * A non pending {@link Conversion} has been successfully retrieved from the
     * service
     * 
     * @param conversion
     *            the non pending {@link Conversion}
     */
    void received(Conversion conversion);

    /**
     * A {@link SubmissionReference} has expired as a result of a limit imposed
     * by the {@link RetrievalStrategy} in use
     * 
     * @param reference
     *            the expired {@link SubmissionReference}
     */
    void expired(SubmissionReference reference);

    /**
     * An exception was encountered while retrieving a
     * {@link SubmissionReference} The {@link SubmissionReference} is still
     * being managed by the {@link SubmissionManager}
     * 
     * @param reference
     *            the {@link SubmissionReference} being retrieved when the
     *            exception occured
     * @param exception
     *            the exception
     */
    void exception(SubmissionReference reference, Exception exception);
}
